home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 007 / xlisp17.arc / XLISP17U.DOC < prev   
Text File  |  1986-06-09  |  59KB  |  1,339 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.                 XLISP: An Experimental Object-oriented Language
  14.  
  15.                                   Version 1.7
  16.  
  17.                                  March 12, 1986
  18.  
  19.  
  20.                                        by
  21.                                David Michael Betz
  22.                                114 Davenport Ave.
  23.                              Manchester, NH  03103
  24.  
  25.                              (603) 625-4691 (home)
  26.  
  27.                    Copyright (c) 1986, by David Michael Betz
  28.                               All Rights Reserved
  29.            Permission is granted for unrestricted non-commercial use
  30.         XLISP                  TABLE OF CONTENTS                  Page 2
  31.  
  32.  
  33.                                Table of Contents
  34.  
  35.  
  36.                 TABLE OF CONTENTS                        2
  37.  
  38.                 INTRODUCTION                             4
  39.  
  40.                 A NOTE FROM THE AUTHOR                   5
  41.  
  42.                 XLISP COMMAND LOOP                       6
  43.  
  44.                 BREAK COMMAND LOOP                       7
  45.  
  46.                 DATA TYPES                               8
  47.  
  48.                 THE EVALUATOR                            9
  49.  
  50.                 LEXICAL CONVENTIONS                     10
  51.  
  52.                 READTABLES                              11
  53.  
  54.                 OBJECTS                                 12
  55.  
  56.                 SYMBOLS                                 15
  57.  
  58.                 EVALUATION FUNCTIONS                    16
  59.  
  60.                 SYMBOL FUNCTIONS                        17
  61.  
  62.                 PROPERTY LIST FUNCTIONS                 19
  63.  
  64.                 ARRAY FUNCTIONS                         20
  65.  
  66.                 LIST FUNCTIONS                          21
  67.  
  68.                 DESTRUCTIVE LIST FUNCTIONS              24
  69.  
  70.                 PREDICATE FUNCTIONS                     25
  71.  
  72.                 CONTROL CONSTRUCTS                      27
  73.  
  74.                 LOOPING CONSTRUCTS                      29
  75.  
  76.                 THE PROGRAM FEATURE                     30
  77.  
  78.                 DEBUGGING AND ERROR HANDLING            31
  79.  
  80.                 ARITHMETIC FUNCTIONS                    32
  81.  
  82.                 BITWISE LOGICAL FUNCTIONS               34
  83.  
  84.                 RELATIONAL FUNCTIONS                    35
  85.  
  86.                 STRING FUNCTIONS                        36
  87.         XLISP                  TABLE OF CONTENTS                  Page 3
  88.  
  89.  
  90.                 INPUT/OUTPUT FUNCTIONS                  37
  91.  
  92.                 FILE I/O FUNCTIONS                      38
  93.  
  94.                 SYSTEM FUNCTIONS                        39
  95.         XLISP                     INTRODUCTION                    Page 4
  96.  
  97.  
  98.         INTRODUCTION
  99.  
  100.         XLISP is an experimental programming language combining some of
  101.         the features of LISP with an object-oriented extension
  102.         capability.  It was implemented to allow experimentation with
  103.         object-oriented programming on small computers.  There are
  104.         currently implementations running on the the VAX under VAX/VMS,
  105.         on the 8088/8086 under MS-DOS, on the 68000 under CP/M-68K, on
  106.         the Macintosh, on the Atari 520ST and on the Amiga.  It is
  107.         completely written in the programming language 'C' and is easily
  108.         extended with user written built-in functions and classes.  It
  109.         is available in source form free of charge to non-commercial
  110.         users.
  111.  
  112.         Many traditional LISP functions are built into XLISP.  In
  113.         addition, XLISP defines the objects 'Object' and 'Class' as
  114.         primitives.  'Object' is the only class that has no superclass
  115.         and hence is the root of the class heirarchy tree.  'Class' is
  116.         the class of which all classes are instances (it is the only
  117.         object that is an instance of itself).
  118.  
  119.         This document is a brief description of XLISP.  It assumes some
  120.         knowledge of LISP and some understanding of the concepts of
  121.         object-oriented programming.
  122.  
  123.         A recommended text for learning LISP programming is the book
  124.         "LISP" by Winston and Horn and published by Addison Wesley.  The
  125.         first edition of this book is based on MacLisp and the second
  126.         edition is based on Common Lisp.  Future versions of XLISP will
  127.         continue to migrate towards compatibility with Common Lisp.
  128.         If you have any problems with XLISP, feel free to contact me for
  129.         help or advice.  Please remember that since XLISP is available
  130.         in source form in a high level language, many users have been
  131.         making versions available on a variety of machines.  If you call
  132.         to report a problem with a specific version, I may not be able
  133.         to help you if that version runs on a machine to which I don't
  134.         have access.  Please have the version number of the version that
  135.         you are running readily accessible before calling me.
  136.  
  137.         If you find a bug in XLISP, first try to fix the bug yourself
  138.         using the source code provided.  If you are successful in fixing
  139.         the bug, send the bug report along with the fix to me.  If you
  140.         don't have access to a C compiler or are unable to fix a bug,
  141.         please send the bug report to me and I'll try to fix it.
  142.  
  143.         Any suggestions for improvements will be welcomed.  Feel free to
  144.         extend the language in whatever way suits your needs.  However,
  145.         PLEASE DO NOT RELEASE ENHANCED VERSIONS WITHOUT CHECKING WITH ME
  146.         FIRST!!  I would like to be the clearing house for new features
  147.         added to XLISP.  If you want to add features for your own
  148.         personal use, go ahead.  But, if you want to distribute your
  149.         enhanced version, contact me first.  Please remember that the
  150.         goal of XLISP is to provide a language to learn and experiment
  151.         with LISP and object-oriented programming on small computers.  I
  152.         don't want it to get so big that it requires megabytes of memory
  153.         to run.
  154.         XLISP                 XLISP COMMAND LOOP                  Page 6
  155.  
  156.  
  157.         XLISP COMMAND LOOP
  158.  
  159.         When XLISP is started, it first tries to load "init.lsp" from
  160.         the default directory.  It then loads any files named as
  161.         parameters on the command line (after appending ".lsp" to their
  162.         names).  It then issues the following prompt:
  163.  
  164.         >
  165.  
  166.         This indicates that XLISP is waiting for an expression to be
  167.         typed.  When an incomplete expression has been typed (one where
  168.         the left and right parens don't match) XLISP changes its prompt
  169.         to:
  170.  
  171.         n>
  172.  
  173.         where n is an integer indicating how many levels of left parens
  174.         remain unclosed.
  175.  
  176.         When a complete expression has been entered, XLISP attempts to
  177.         evaluate that expression.  If the expression evaluates
  178.         successfully, XLISP prints the result of the evaluation and then
  179.         returns to the initial prompt waiting for another expression to
  180.         be typed.
  181.  
  182.         XLISP                 BREAK COMMAND LOOP                  Page 7
  183.  
  184.  
  185.         BREAK COMMAND LOOP
  186.  
  187.         When XLISP encounters an error while evaluating an expression,
  188.         it attempts to handle the error in the following way:
  189.  
  190.         If the symbol '*breakenable*' is true, the message corresponding
  191.         to the error is printed.  If the error is correctable, the
  192.         correction message is printed.  If the symbol '*tracenable*' is
  193.         true, a trace back is printed.  The number of entries printed
  194.         depends on the value of the symbol '*tracelimit*'.  If this
  195.         symbol is set to something other than a number, the entire trace
  196.         back stack is printed.  XLISP then enters a read/eval/print loop
  197.         to allow the user to examine the state of the interpreter in the
  198.         context of the error.  This loop differs from the normal top-
  199.         level read/eval/print loop in that if the user invokes the
  200.         function 'continue', XLISP will continue from a correctable
  201.         error.  If the user invokes the function 'clean-up', XLISP will
  202.         abort the break loop and return to the top level or the next
  203.         lower numbered break loop.  When in a break loop, XLISP prefixes
  204.         the break level to the normal prompt.
  205.  
  206.         If the symbol '*breakenable*' is nil, XLISP looks for a
  207.         surrounding errset function.  If one is found, XLISP examines
  208.         the value of the print flag.  If this flag is true, the error
  209.         message is printed.  In any case, XLISP causes the errset
  210.         function call to return nil.
  211.  
  212.         If there is no surrounding errset function, XLISP prints the
  213.         error message and returns to the top level.
  214.         XLISP                      DATA TYPES                     Page 8
  215.  
  216.  
  217.         DATA TYPES
  218.  
  219.         There are several different data types available to XLISP
  220.         programmers.
  221.  
  222.             o lists
  223.             o symbols
  224.             o strings
  225.             o integers
  226.             o floats
  227.             o objects
  228.             o arrays
  229.             o file pointers
  230.             o subrs (built-in functions)
  231.             o fsubrs (special forms)
  232.  
  233.         Another data type is the stream.  A stream is a list node whose
  234.         car points to the head of a list of integers and whose cdr
  235.         points to the last list node of the list.  An empty stream is a
  236.         list node whose car and cdr are nil.  Each of the integers in
  237.         the list represents a character in the stream.  When a character
  238.         is read from a stream, the first integer from the head of the
  239.         list is removed and returned.  When a character is written to a
  240.         stream, the integer representing the character code of the
  241.         character is appended to the end of the list.  When a function
  242.         indicates that it takes an input source as a parameter, this
  243.         parameter can either be an input file pointer or a stream.
  244.         Similarly, when a function indicates that it takes an output
  245.         sink as a parameter, this parameter can either be an output file
  246.         pointer or a stream.
  247.         XLISP                    THE EVALUATOR                    Page 9
  248.  
  249.  
  250.         THE EVALUATOR
  251.  
  252.         The process of evaluation in XLISP:
  253.  
  254.         Integers, floats, strings, file pointers, subrs, fsubrs, objects
  255.         and arrays evaluate to themselves
  256.  
  257.         Symbols evaluate to the value associated with their current
  258.         binding
  259.  
  260.         Lists are evaluated by evaluating the first element of the list
  261.         and then taking one of the following actions:
  262.  
  263.             If it is a subr, the remaining list elements are evaluated
  264.             and the subr is called with these evaluated expressions as
  265.             arguments.
  266.  
  267.             If it is an fsubr, the fsubr is called using the remaining
  268.             list elements as arguments (unevaluated)
  269.  
  270.             If it is a list:
  271.  
  272.                 If the list is a function closure (a list whose car is a
  273.                 lambda expression and whose cdr is an environment list),
  274.                 the car of the list is used as the function to be
  275.                 applied and the cdr is used as the environment to be
  276.                 extended with the parameter bindings.
  277.  
  278.                 If the list is a lambda expression, the current
  279.                 environment is used for the function application.
  280.  
  281.                     In either of the above two cases, the remaining list
  282.                     elements are evaluated and the resulting expressions
  283.                     are bound to the formal arguments of the lambda
  284.                     expression.  The body of the function is executed
  285.                     within this new binding environment.
  286.  
  287.                 If it is a list and the car of the list is 'macro', the
  288.                 remaining list elements are bound to the formal
  289.                 arguments of the macro expression.  The body of the
  290.                 function is executed within this new binding
  291.                 environment.  The result of this evaluation is
  292.                 considered the macro expansion.  This result is then
  293.                 evaluated in place of the original expression.
  294.  
  295.                 If it is an object, the second list element is evaluated
  296.                 and used as a message selector.  The message formed by
  297.                 combining the selector with the values of the remaining
  298.                 list elements is sent to the object.
  299.         XLISP                 LEXICAL CONVENTIONS                Page 10
  300.  
  301.  
  302.         LEXICAL CONVENTIONS
  303.  
  304.         The following conventions must be followed when entering XLISP
  305.         programs:
  306.  
  307.         Comments in XLISP code begin with a semi-colon character and
  308.         continue to the end of the line.
  309.  
  310.         Symbol names in XLISP can consist of any sequence of non-blank
  311.         printable characters except the following:
  312.  
  313.                 ( ) ' ` , " ;
  314.  
  315.         Uppercase and lowercase characters are not distinguished within
  316.         symbol names.  All lowercase characters are mapped to uppercase
  317.         on input.
  318.  
  319.         Integer literals consist of a sequence of digits optionally
  320.         beginning with a '+' or '-'.  The range of values an integer can
  321.         represent is limited by the size of a C 'long' on the machine on
  322.         which XLISP is running.
  323.  
  324.         Floating point literals consist of a sequence of digits
  325.         optionally beginning with a '+' or '-' and including an embedded
  326.         decimal point.  The range of values a floating point number can
  327.         represent is limited by the size of a C 'float' ('double' on
  328.         machines with 32 bit addresses) on the machine on which XLISP is
  329.         running.
  330.  
  331.         Literal strings are sequences of characters surrounded by double
  332.         quotes.  Within quoted strings the '' character is used to allow
  333.         non-printable characters to be included.  The codes recognized
  334.         are:
  335.  
  336.                 \\        means the character '\'
  337.                 \n       means newline
  338.                 \t       means tab
  339.                 \r       means return
  340.                 \f       means form feed
  341.                 \nnn     means the character whose octal code is nnn
  342.  
  343.         XLISP defines several useful read macros:
  344.  
  345.                 '<expr>         == (quote <expr>)
  346.                 #'<expr>        == (function <expr>)
  347.                 #(<expr>...)    == an array of the specified expressions
  348.                 #x<hdigits>     == a hexadecimal number
  349.                 #\<char> == the ASCII code of the character
  350.                 `<expr>         == (backquote <expr>)
  351.                 ,<expr>         == (comma <expr>)
  352.                 ,@<expr>        == (comma-at <expr>)
  353.         XLISP                      READTABLES                    Page 11
  354.  
  355.  
  356.         READTABLES
  357.  
  358.         The behaviour of the reader is controlled by a data structure
  359.         called a "readtable".  The reader uses the symbol *READTABLE* to
  360.         locate the current readtable.  This table controls the
  361.         interpretation of input characters.  It is an array with 128
  362.         entries, one for each of the ASCII character codes.  Each entry
  363.         contains one of the following things:
  364.  
  365.                 NIL             Indicating an invalid character
  366.                 :CONSTITUENT    Indicating a symbol constituent
  367.                 :WHITE-SPACE    Indicating a whitespace character
  368.                 (:TMACRO . fun) Terminating readmacro
  369.                 (:NMACRO . fun) Non-terminating readmacro
  370.  
  371.         In the case of the last two forms, the "fun" component is a
  372.         function definition.  This can either be a pointer to a built-in
  373.         readmacro function or a lambda expression.  The function should
  374.         take two parameters.  The first is the input stream and the
  375.         second is the character that caused the invocation of the
  376.         readmacro.  The character is passed as an integer.  The
  377.         readmacro function should return NIL to indicate that the
  378.         character should be treated as white space or a value consed
  379.         with NIL to indicate that the readmacro should be treated as an
  380.         occurance of the specified value.  Of course, the readmacro code
  381.         is free to read additional characters from the input stream.
  382.         XLISP                       OBJECTS                      Page 12
  383.  
  384.  
  385.         OBJECTS
  386.  
  387.         Definitions:
  388.  
  389.             o selector - a symbol used to select an appropriate method
  390.             o message - a selector and a list of actual arguments
  391.             o method - the code that implements a message
  392.  
  393.         Since XLISP was created to provide a simple basis for
  394.         experimenting with object-oriented programming, one of the
  395.         primitive data types included is 'object'.  In XLISP, an object
  396.         consists of a data structure containing a pointer to the
  397.         object's class as well as an array containing the values of the
  398.         object's instance variables.
  399.  
  400.         Officially, there is no way to see inside an object (look at the
  401.         values of its instance variables).  The only way to communicate
  402.         with an object is by sending it a message.  When the XLISP
  403.         evaluator evaluates a list the value of whose first element is
  404.         an object, it interprets the value of the second element of the
  405.         list (which must be a symbol) as the message selector.  The
  406.         evaluator determines the class of the receiving object and
  407.         attempts to find a method corresponding to the message selector
  408.         in the set of messages defined for that class.  If the message
  409.         is not found in the object's class and the class has a super-
  410.         class, the search continues by looking at the messages defined
  411.         for the super-class.  This process continues from one super-
  412.         class to the next until a method for the message is found.  If
  413.         no method is found, an error occurs.
  414.  
  415.         When a method is found, the evaluator binds the receiving object
  416.         to the symbol 'self', binds the class in which the method was
  417.         found to the symbol 'msgclass', and evaluates the method using
  418.         the remaining elements of the original list as arguments to the
  419.         method.  These arguments are always evaluated prior to being
  420.         bound to their corresponding formal arguments.  The result of
  421.         evaluating the method becomes the result of the expression.
  422.         XLISP                       OBJECTS                      Page 13
  423.  
  424.  
  425.         THE 'Object' CLASS
  426.  
  427.         Classes:
  428.  
  429.         Object  THE TOP OF THE CLASS HEIRARCHY
  430.  
  431.             Messages:
  432.  
  433.                 :show  SHOW AN OBJECT'S INSTANCE VARIABLES
  434.                     returns     the object
  435.  
  436.                 :class  RETURN THE CLASS OF AN OBJECT
  437.                     returns     the class of the object
  438.  
  439.                 :isnew  THE DEFAULT OBJECT INITIALIZATION ROUTINE
  440.                     returns     the object
  441.  
  442.                 :sendsuper <sel> [<args>]...  SEND SUPERCLASS A MESSAGE
  443.                     <sel>       the message selector
  444.                     <args>      the message arguments
  445.                     returns     the result of sending the message
  446.         XLISP                       OBJECTS                      Page 14
  447.  
  448.  
  449.         THE 'Class' CLASS
  450.  
  451.         Class   THE CLASS OF ALL OBJECT CLASSES (including itself)
  452.  
  453.             Messages:
  454.  
  455.                 :new  CREATE A NEW INSTANCE OF A CLASS
  456.                     returns     the new class object
  457.  
  458.                 :isnew <ivars> [<cvars>[<super>]]  INITIALIZE A NEW CLASS
  459.                     <ivars>     the list of instance variable symbols
  460.                     <cvars>     the list of class variable symbols
  461.                     <super>     the superclass (default is Object)
  462.                     returns     the new class object
  463.  
  464.                 :answer <msg> <fargs> <code>  ADD A MESSAGE TO A CLASS
  465.                     <msg>       the message symbol
  466.                     <fargs>     the formal argument list
  467.                                   this list is of the form:
  468.                                     ([<farg>]...
  469.                                      [&optional [<oarg>]...]
  470.                                      [&rest <rarg>]
  471.                                      [&aux [<aux>]...])
  472.                                   where
  473.                                     <farg>   a formal argument
  474.                                     <oarg>   an optional argument
  475.                                     <rarg>   bound to rest of the arguments
  476.                                     <aux>    a auxiliary variable
  477.                     <code>      a list of executable expressions
  478.                     returns     the object
  479.  
  480.  
  481.         When a new instance of a class is created by sending the message
  482.         ':new' to an existing class, the message ':isnew' followed by
  483.         whatever parameters were passed to the ':new' message is sent to
  484.         the newly created object.
  485.  
  486.         When a new class is created by sending the ':new' message to the
  487.         object 'Class', an optional parameter may be specified
  488.         indicating the superclass of the new class.  If this parameter
  489.         is omitted, the new class will be a subclass of 'Object'.  A
  490.         class inherits all instance variables, class variables, and
  491.         methods from its super-class.
  492.         XLISP                       SYMBOLS                      Page 15
  493.  
  494.  
  495.         SYMBOLS
  496.  
  497.             o self - the current object (within a message context)
  498.             o msgclass - the class in which the current method was found
  499.             o *obarray* - the object hash table
  500.             o *standard-input* - the standard input file
  501.             o *standard-output* - the standard output file
  502.             o *breakenable* - flag controlling entering break loop on errors
  503.             o *tracenable* - enable baktrace on errors
  504.             o *tracelimit* - number of levels of trace back information
  505.             o *evalhook* - user substitute for the evaluator function
  506.             o *applyhook* - (not yet implemented)
  507.             o *readtable* - the current readtable
  508.             o *unbound* - indicator for unbound symbols
  509.             o *gc-flag* - controls the printing of gc messages
  510.  
  511.         XLISP                 EVALUATION FUNCTIONS               Page 16
  512.  
  513.  
  514.         EVALUATION FUNCTIONS
  515.  
  516.         (eval <expr>)  EVALUATE AN XLISP EXPRESSION
  517.             <expr>      the expression to be evaluated
  518.             returns     the result of evaluating the expression
  519.  
  520.         (apply <fun> <args>)  APPLY A FUNCTION TO A LIST OF ARGUMENTS
  521.             <fun>       the function to apply (or function symbol)
  522.             <args>      the argument list
  523.             returns     the result of applying the function to the arguments
  524.  
  525.         (funcall <fun> [<arg>]...)  CALL A FUNCTION WITH ARGUMENTS
  526.             <fun>       the function to call (or function symbol)
  527.             <arg>       arguments to pass to the function
  528.             returns     the result of calling the function with the arguments
  529.  
  530.         (quote <expr>)  RETURN AN EXPRESSION UNEVALUATED
  531.             <expr>      the expression to be quoted (quoted)
  532.             returns     <expr> unevaluated
  533.  
  534.         (function <expr>)  QUOTE A FUNCTION
  535.             <expr>      the function to be quoted (quoted)
  536.             returns     a function closure
  537.  
  538.         (backquote <expr>)  FILL IN A TEMPLATE
  539.             <expr>      the template
  540.             returns     a copy of the template with comma and comma-at
  541.                         expressions expanded
  542.  
  543.         (lambda <args> [<expr>]...)  MAKE A FUNCTION CLOSURE
  544.             <args>      the argument list (quoted)
  545.             <expr>      expressions of the function body
  546.             returns     the function closure
  547.         XLISP                   SYMBOL FUNCTIONS                 Page 17
  548.  
  549.  
  550.         SYMBOL FUNCTIONS
  551.  
  552.         (set <sym> <expr>)  SET THE VALUE OF A SYMBOL
  553.             <sym>       the symbol being set
  554.             <expr>      the new value
  555.             returns     the new value
  556.  
  557.         (setq [<sym> <expr>]...)  SET THE VALUE OF A SYMBOL
  558.             <sym>       the symbol being set (quoted)
  559.             <expr>      the new value
  560.             returns     the new value
  561.  
  562.         (setf [<place> <expr>]...)  SET THE VALUE OF A FIELD
  563.             <place>     the field specifier (quoted):
  564.                             <sym>                set value of a symbol
  565.                             (car <expr>)         set car of a list node
  566.                             (cdr <expr>)         set cdr of a list node
  567.                             (nth <n> <expr>)     set nth car of a list
  568.                             (aref <expr> <n>)    set nth element of an array
  569.                             (get <sym> <prop>)   set value of a property
  570.                             (symbol-value <sym>) set value of a symbol
  571.                             (symbol-plist <sym>) set property list of a symbol
  572.             <value>     the new value
  573.             returns     the new value
  574.  
  575.         (defun <sym> <fargs> [<expr>]...)  DEFINE A FUNCTION
  576.         (defmacro <sym> <fargs> [<expr>]...)  DEFINE A MACRO
  577.             <sym>       symbol being defined (quoted)
  578.             <fargs>     list of formal arguments (quoted)
  579.                           this list is of the form:
  580.                             ([<farg>]...
  581.                              [&optional [<oarg>]...]
  582.                              [&rest <rarg>]
  583.                              [&aux [<aux>]...])
  584.                           where
  585.                             <farg>      is a formal argument
  586.                             <oarg>      is an optional argument
  587.                             <rarg>      bound to the rest of the arguments
  588.                             <aux>       is an auxiliary variable
  589.             <expr>      expressions constituting the body of the
  590.                         function (quoted)
  591.             returns     the function symbol
  592.  
  593.         (gensym [<tag>])  GENERATE A SYMBOL
  594.             <tag>       string or number
  595.             returns     the new symbol
  596.  
  597.         (intern <pname>)  MAKE AN INTERNED SYMBOL
  598.             <pname>     the symbol's print name string
  599.             returns     the new symbol
  600.  
  601.         (make-symbol <pname>)  MAKE AN UNINTERNED SYMBOL
  602.             <pname>     the symbol's print name string
  603.             returns     the new symbol
  604.         XLISP                   SYMBOL FUNCTIONS                 Page 18
  605.  
  606.  
  607.         (symbol-name <sym>)  GET THE PRINT NAME OF A SYMBOL
  608.             <sym>       the symbol
  609.             returns     the symbol's print name
  610.  
  611.         (symbol-value <sym>)  GET THE VALUE OF A SYMBOL
  612.             <sym>       the symbol
  613.             returns     the symbol's value
  614.  
  615.         (symbol-plist <sym>)  GET THE PROPERTY LIST OF A SYMBOL
  616.             <sym>       the symbol
  617.             returns     the symbol's property list
  618.  
  619.         (hash <sym> <n>)  COMPUTE THE HASH INDEX FOR A SYMBOL
  620.             <sym>       the symbol or string
  621.             <n>         the table size (integer)
  622.             returns     the hash index (integer)
  623.  
  624.         XLISP               PROPERTY LIST FUNCTIONS              Page 19
  625.  
  626.  
  627.         PROPERTY LIST FUNCTIONS
  628.  
  629.         (get <sym> <prop>)  GET THE VALUE OF A PROPERTY
  630.             <sym>       the symbol
  631.             <prop>      the property symbol
  632.             returns     the property value or nil
  633.  
  634.         (putprop <sym> <val> <prop>)  PUT A PROPERTY ONTO A PROPERTY LIST
  635.             <sym>       the symbol
  636.             <val>       the property value
  637.             <prop>      the property symbol
  638.             returns     the property value
  639.  
  640.         (remprop <sym> <prop>)  REMOVE A PROPERTY
  641.             <sym>       the symbol
  642.             <prop>      the property symbol
  643.             returns     nil
  644.         XLISP                   ARRAY FUNCTIONS                  Page 20
  645.  
  646.  
  647.         ARRAY FUNCTIONS
  648.  
  649.         (aref <array> <n>)  GET THE NTH ELEMENT OF AN ARRAY
  650.             <array>     the array
  651.             <n>         the array index (integer)
  652.             returns     the value of the array element
  653.  
  654.         (make-array <size>)  MAKE A NEW ARRAY
  655.             <size>      the size of the new array (integer)
  656.             returns     the new array
  657.         XLISP                    LIST FUNCTIONS                  Page 21
  658.  
  659.  
  660.         LIST FUNCTIONS
  661.  
  662.         (car <expr>)  RETURN THE CAR OF A LIST NODE
  663.             <expr>      the list node
  664.             returns     the car of the list node
  665.  
  666.         (cdr <expr>)  RETURN THE CDR OF A LIST NODE
  667.             <expr>      the list node
  668.             returns     the cdr of the list node
  669.  
  670.         (cxxr <expr>)  ALL CxxR COMBINATIONS
  671.         (cxxxr <expr>)  ALL CxxxR COMBINATIONS
  672.         (cxxxxr <expr>)  ALL CxxxxR COMBINATIONS
  673.  
  674.         (cons <expr1> <expr2>)  CONSTRUCT A NEW LIST NODE
  675.             <expr1>     the car of the new list node
  676.             <expr2>     the cdr of the new list node
  677.             returns     the new list node
  678.  
  679.         (list [<expr>]...)  CREATE A LIST OF VALUES
  680.             <expr>      expressions to be combined into a list
  681.             returns     the new list
  682.  
  683.         (append [<expr>]...)  APPEND LISTS
  684.             <expr>      lists whose elements are to be appended
  685.             returns     the new list
  686.  
  687.         (reverse <expr>)  REVERSE A LIST
  688.             <expr>      the list to reverse
  689.             returns     a new list in the reverse order
  690.  
  691.         (last <list>)  RETURN THE LAST LIST NODE OF A LIST
  692.             <list>      the list
  693.             returns     the last list node in the list
  694.  
  695.         (member <expr> <list> [<key> <test>])  FIND AN EXPRESSION IN A LIST
  696.             <expr>      the expression to find
  697.             <list>      the list to search
  698.             <key>       the keyword :test or :test-not
  699.             <test>      the test function (defaults to eql)
  700.             returns     the remainder of the list starting with the expression
  701.  
  702.         (assoc <expr> <alist> [<key> <test>])  FIND AN EXPRESSION IN AN A-LIST
  703.             <expr>      the expression to find
  704.             <alist>     the association list
  705.             <key>       the keyword :test or :test-not
  706.             <test>      the test function (defaults to eql)
  707.             returns     the alist entry or nil
  708.         XLISP                    LIST FUNCTIONS                  Page 22
  709.  
  710.  
  711.         (remove <expr> <list> [<key> <test>])  REMOVE AN EXPRESSION
  712.             <expr>      the expression to delete
  713.             <list>      the list
  714.             <key>       the keyword :test or :test-not
  715.             <test>      the test function (defaults to eql)
  716.             returns     the list with the matching expressions deleted
  717.  
  718.         (length <expr>)  FIND THE LENGTH OF A LIST OR STRING
  719.             <expr>      the list or string
  720.             returns     the length of the list or string
  721.  
  722.         (nth <n> <list>)  RETURN THE NTH ELEMENT OF A LIST
  723.             <n>         the number of the element to return (zero origin)
  724.             <list>      the list
  725.             returns     the nth element or nil if the list isn't that long
  726.  
  727.         (nthcdr <n> <list>)  RETURN THE NTH CDR OF A LIST
  728.             <n>         the number of the element to return (zero origin)
  729.             <list>      the list
  730.             returns     the nth cdr or nil if the list isn't that long
  731.  
  732.         (mapc <fcn> <list1> [<list>]...)  APPLY FUNCTION TO SUCCESSIVE CARS
  733.             <fcn>       the function or function name
  734.             <listn>     a list for each argument of the function
  735.             returns     the first list of arguments
  736.  
  737.         (mapcar <fcn> <list1> [<list>]...)  APPLY FUNCTION TO SUCCESSIVE CARS
  738.             <fcn>       the function or function name
  739.             <listn>     a list for each argument of the function
  740.             returns     a list of the values returned
  741.  
  742.         (mapl <fcn> <list1> [<list>]...)  APPLY FUNCTION TO SUCCESSIVE CDRS
  743.             <fcn>       the function or function name
  744.             <listn>     a list for each argument of the function
  745.             returns     the first list of arguments
  746.  
  747.         (maplist <fcn> <list1> [<list>]...)  APPLY FUNCTION TO SUCCESSIVE CDRS
  748.             <fcn>       the function or function name
  749.             <listn>     a list for each argument of the function
  750.             returns     a list of the values returned
  751.         XLISP                    LIST FUNCTIONS                  Page 23
  752.  
  753.  
  754.         (subst <to> <from> <expr> [<key> <test>])  SUBSTITUTE EXPRESSIONS
  755.             <to>        the new expression
  756.             <from>      the old expression
  757.             <expr>      the expression in which to do the substitutions
  758.             <key>       the keyword :test or :test-not
  759.             <test>      the test function (defaults to eql)
  760.             returns     the expression with substitutions
  761.  
  762.         (sublis <alist> <expr> [<key> <test>])  SUBSTITUTE WITH AN A-LIST
  763.             <alist>     the association list
  764.             <expr>      the expression in which to do the substitutions
  765.             <key>       the keyword :test or :test-not
  766.             <test>      the test function (defaults to eql)
  767.             returns     the expression with substitutions
  768.         XLISP              DESTRUCTIVE LIST FUNCTIONS            Page 24
  769.  
  770.  
  771.         DESTRUCTIVE LIST FUNCTIONS
  772.  
  773.         (rplaca <list> <expr>)  REPLACE THE CAR OF A LIST NODE
  774.             <list>      the list node
  775.             <expr>      the new value for the car of the list node
  776.             returns     the list node after updating the car
  777.  
  778.         (rplacd <list> <expr>)  REPLACE THE CDR OF A LIST NODE
  779.             <list>      the list node
  780.             <expr>      the new value for the cdr of the list node
  781.             returns     the list node after updating the cdr
  782.  
  783.         (nconc [<list>]...)  DESTRUCTIVELY CONCATENATE LISTS
  784.             <list>      lists to concatenate
  785.             returns     the result of concatenating the lists
  786.  
  787.         (delete <expr> <list> [<key> <test>])  DELETE AN EXPRESSION FROM A LIST
  788.             <expr>      the expression to delete
  789.             <list>      the list
  790.             <key>       the keyword :test or :test-not
  791.             <test>      the test function (defaults to eql)
  792.             returns     the list with the matching expressions deleted
  793.         XLISP                 PREDICATE FUNCTIONS                Page 25
  794.  
  795.  
  796.         PREDICATE FUNCTIONS
  797.  
  798.         (atom <expr>)  IS THIS AN ATOM?
  799.             <expr>      the expression to check
  800.             returns     t if the value is an atom, nil otherwise
  801.  
  802.         (symbolp <expr>)  IS THIS A SYMBOL?
  803.             <expr>      the expression to check
  804.             returns     t if the expression is a symbol, nil otherwise
  805.  
  806.         (numberp <expr>)  IS THIS A NUMBER?
  807.             <expr>      the expression to check
  808.             returns     t if the expression is a number, nil otherwise
  809.  
  810.         (null <expr>)  IS THIS AN EMPTY LIST?
  811.             <expr>      the list to check
  812.             returns     t if the list is empty, nil otherwise
  813.  
  814.         (not <expr>)  IS THIS FALSE?
  815.             <expr>      the expression to check
  816.             return      t if the expression is nil, nil otherwise
  817.  
  818.         (listp <expr>)  IS THIS A LIST?
  819.             <expr>      the expression to check
  820.             returns     t if the value is a list node or nil, nil otherwise
  821.  
  822.         (consp <expr>)  IS THIS A NON-EMPTY LIST?
  823.             <expr>      the expression to check
  824.             returns     t if the value is a list node, nil otherwise
  825.  
  826.         (boundp <sym>)  IS THIS A BOUND SYMBOL?
  827.             <sym>       the symbol
  828.             returns     t if a value is bound to the symbol, nil otherwise
  829.         XLISP                 PREDICATE FUNCTIONS                Page 26
  830.  
  831.  
  832.         (minusp <expr>)  IS THIS NUMBER NEGATIVE?
  833.             <expr>      the number to test
  834.             returns     t if the number is negative, nil otherwise
  835.  
  836.         (zerop <expr>)  IS THIS NUMBER ZERO?
  837.             <expr>      the number to test
  838.             returns     t if the number is zero, nil otherwise
  839.  
  840.         (plusp <expr>)  IS THIS NUMBER POSITIVE?
  841.             <expr>      the number to test
  842.             returns     t if the number is positive, nil otherwise
  843.  
  844.         (evenp <expr>)  IS THIS NUMBER EVEN?
  845.             <expr>      the number to test
  846.             returns     t if the number is even, nil otherwise
  847.  
  848.         (oddp <expr>)  IS THIS NUMBER ODD?
  849.             <expr>      the number to test
  850.             returns     t if the number is odd, nil otherwise
  851.  
  852.         (eq <expr1> <expr2>)  ARE THE EXPRESSIONS IDENTICAL?
  853.             <expr1>     the first expression
  854.             <expr2>     the second expression
  855.             returns     t if they are equal, nil otherwise
  856.  
  857.         (eql <expr1> <expr2>)  ARE THE EXPRESSIONS IDENTICAL?
  858.                                 (WORKS WITH NUMBERS AND STRINGS)
  859.             <expr1>     the first expression
  860.             <expr2>     the second expression
  861.             returns     t if they are equal, nil otherwise
  862.  
  863.         (equal <expr1> <expr2>)  ARE THE EXPRESSIONS EQUAL?
  864.             <expr1>     the first expression
  865.             <expr2>     the second expression
  866.             returns     t if they are equal, nil otherwise
  867.         XLISP                  CONTROL CONSTRUCTS                Page 27
  868.  
  869.  
  870.         CONTROL CONSTRUCTS
  871.  
  872.         (cond [<pair>]...)  EVALUATE CONDITIONALLY
  873.             <pair>      pair consisting of:
  874.                             (<pred> [<expr>]...)
  875.                           where
  876.                             <pred>      is a predicate expression
  877.                             <expr>      evaluated if the predicate
  878.                                         is not nil
  879.             returns     the value of the first expression whose predicate
  880.                         is not nil
  881.  
  882.         (and [<expr>]...)  THE LOGICAL AND OF A LIST OF EXPRESSIONS
  883.             <expr>      the expressions to be ANDed
  884.             returns     nil if any expression evaluates to nil,
  885.                         otherwise the value of the last expression
  886.                         (evaluation of expressions stops after the first
  887.                          expression that evaluates to nil)
  888.  
  889.         (or [<expr>]...)  THE LOGICAL OR OF A LIST OF EXPRESSIONS
  890.             <expr>      the expressions to be ORed
  891.             returns     nil if all expressions evaluate to nil,
  892.                         otherwise the value of the first non-nil expression
  893.                         (evaluation of expressions stops after the first
  894.                          expression that does not evaluate to nil)
  895.  
  896.         (if <texpr> <expr1> [<expr2>])  EXECUTE EXPRESSIONS CONDITIONALLY
  897.             <texpr>     the test expression
  898.             <expr1>     the expression to be evaluated if texpr is non-nil
  899.             <expr2>     the expression to be evaluated if texpr is nil
  900.             returns     the value of the selected expression
  901.  
  902.         (case <expr> [<case>]...)  SELECT BY CASE
  903.             <expr>      the selection expression
  904.             <case>      pair consisting of:
  905.                             (<value> [<expr>]...)
  906.                           where:
  907.                             <value>     is a single expression or a list of
  908.                                         expressions (unevaluated)
  909.                             <expr>      are expressions to execute if the
  910.                                         case matches
  911.             returns     the value of the last expression of the matching case
  912.  
  913.         (let ([<binding>]...) [<expr>]...)  CREATE LOCAL BINDINGS
  914.         (let* ([<binding>]...) [<expr>]...)  LET WITH SEQUENTIAL BINDING
  915.             <binding>   the variable bindings each of which is either:
  916.                         1)  a symbol (which is initialized to nil)
  917.                         2)  a list whose car is a symbol and whose cadr
  918.                                 is an initialization expression
  919.             <expr>      the expressions to be evaluated
  920.             returns     the value of the last expression
  921.  
  922.         (catch <sym> [<expr>]...)  EVALUATE EXPRESSIONS AND CATCH THROWS
  923.             <sym>       the catch tag
  924.         XLISP                  CONTROL CONSTRUCTS                Page 28
  925.  
  926.  
  927.             <expr>      expressions to evaluate
  928.             returns     the value of the last expression the throw expression
  929.  
  930.         (throw <sym> [<expr>])  THROW TO A CATCH
  931.             <sym>       the catch tag
  932.             <expr>      the value for the catch to return (defaults to nil)
  933.             returns     never returns
  934.         XLISP                  LOOPING CONSTRUCTS                Page 29
  935.  
  936.  
  937.         LOOPING CONSTRUCTS
  938.  
  939.         (do ([<binding>]...) (<texpr> [<rexpr>]...) [<expr>]...)
  940.         (do* ([<binding>]...) (<texpr> [<rexpr>]...) [<expr>]...)
  941.             <binding>   the variable bindings each of which is either:
  942.                         1)  a symbol (which is initialized to nil)
  943.                         2)  a list of the form: (<sym> <init> [<step>])
  944.                             where:
  945.                                 <sym>  is the symbol to bind
  946.                                 <init> is the initial value of the symbol
  947.                                 <step> is a step expression
  948.             <texpr>     the termination test expression
  949.             <rexpr>     result expressions (the default is nil)
  950.             <expr>      the body of the loop (treated like an implicit prog)
  951.             returns     the value of the last result expression
  952.  
  953.         (dolist (<sym> <expr> [<rexpr>]) [<expr>]...)  LOOP THROUGH A LIST
  954.             <sym>       the symbol to bind to each list element
  955.             <expr>      the list expression
  956.             <rexpr>     the result expression (the default is nil)
  957.             <expr>      the body of the loop (treated like an implicit prog)
  958.  
  959.         (dotimes (<sym> <expr> [<rexpr>]) [<expr>]...)  LOOP FROM ZERO TO N-1
  960.             <sym>       the symbol to bind to each value from 0 to n-1
  961.             <expr>      the number of times to loop
  962.             <rexpr>     the result expression (the default is nil)
  963.             <expr>      the body of the loop (treated like an implicit prog)
  964.         XLISP                 THE PROGRAM FEATURE                Page 30
  965.  
  966.  
  967.         THE PROGRAM FEATURE
  968.  
  969.         (prog ([<binding>]...) [<expr>]...)  THE PROGRAM FEATURE
  970.         (prog* ([<binding>]...) [<expr>]...)  PROG WITH SEQUENTIAL BINDING
  971.             <binding>   the variable bindings each of which is either:
  972.                         1)  a symbol (which is initialized to nil)
  973.                         2)  a list whose car is a symbol and whose cadr
  974.                                 is an initialization expression
  975.             <expr>      expressions to evaluate or tags (symbols)
  976.             returns     nil or the argument passed to the return function
  977.  
  978.         (go <sym>)  GO TO A TAG WITHIN A PROG CONSTRUCT
  979.             <sym>       the tag (quoted)
  980.             returns     never returns
  981.  
  982.         (return [<expr>])  CAUSE A PROG CONSTRUCT TO RETURN A VALUE
  983.             <expr>      the value (defaults to nil)
  984.             returns     never returns
  985.  
  986.         (prog1 <expr1> [<expr>]...)  EXECUTE EXPRESSIONS SEQUENTIALLY
  987.             <expr1>     the first expression to evaluate
  988.             <expr>      the remaining expressions to evaluate
  989.             returns     the value of the first expression
  990.  
  991.         (prog2 <expr1> <expr2> [<expr>]...)  EXECUTE EXPRESSIONS SEQUENTIALLY
  992.             <expr1>     the first expression to evaluate
  993.             <expr2>     the second expression to evaluate
  994.             <expr>      the remaining expressions to evaluate
  995.             returns     the value of the second expression
  996.  
  997.         (progn [<expr>]...)  EXECUTE EXPRESSIONS SEQUENTIALLY
  998.             <expr>      the expressions to evaluate
  999.             returns     the value of the last expression (or nil)
  1000.         XLISP             DEBUGGING AND ERROR HANDLING           Page 31
  1001.  
  1002.  
  1003.         DEBUGGING AND ERROR HANDLING
  1004.  
  1005.         (error <emsg> [<arg>])  SIGNAL A NON-CORRECTABLE ERROR
  1006.             <emsg>      the error message string
  1007.             <arg>       the argument expression (printed after the message)
  1008.             returns     never returns
  1009.  
  1010.         (cerror <cmsg> <emsg> [<arg>])  SIGNAL A CORRECTABLE ERROR
  1011.             <cmsg>      the continue message string
  1012.             <emsg>      the error message string
  1013.             <arg>       the argument expression (printed after the message)
  1014.             returns     nil when continued from the break loop
  1015.  
  1016.         (break [<bmsg> [<arg>]])  ENTER A BREAK LOOP
  1017.             <bmsg>      the break message string (defaults to "**BREAK**")
  1018.             <arg>       the argument expression (printed after the message)
  1019.             returns     nil when continued from the break loop
  1020.  
  1021.         (clean-up)  CLEAN-UP AFTER AN ERROR
  1022.             returns     never returns
  1023.  
  1024.         (continue)  CONTINUE FROM A CORRECTABLE ERROR
  1025.             returns     never returns
  1026.  
  1027.         (errset <expr> [<pflag>])  TRAP ERRORS
  1028.             <expr>      the expression to execute
  1029.             <pflag>     flag to control printing of the error message
  1030.             returns     the value of the last expression consed with nil
  1031.                         or nil on error
  1032.  
  1033.         (baktrace [<n>])  PRINT N LEVELS OF TRACE BACK INFORMATION
  1034.             <n>         the number of levels (defaults to all levels)
  1035.             returns     nil
  1036.  
  1037.         (evalhook <expr> <ehook> <ahook> [<env>])  EVALUATE WITH HOOKS
  1038.             <expr>      the expression to evaluate
  1039.             <ehook>     the value for *evalhook*
  1040.             <ahook>     the value for *applyhook*
  1041.             <env>       the environment (default is nil)
  1042.             returns     the result of evaluating the expression
  1043.         XLISP                 ARITHMETIC FUNCTIONS               Page 32
  1044.  
  1045.  
  1046.         ARITHMETIC FUNCTIONS
  1047.  
  1048.         (truncate <expr>)  TRUNCATES A FLOATING POINT NUMBER TO AN INTEGER
  1049.             <expr>      the number
  1050.             returns     the result of truncating the number
  1051.  
  1052.         (float <expr>)  CONVERTS AN INTEGER TO A FLOATING POINT NUMBER
  1053.             <expr>      the number
  1054.             returns     the result of floating the integer
  1055.  
  1056.         (+ <expr>...)  ADD A LIST OF NUMBERS
  1057.             <expr>      the numbers
  1058.             returns     the result of the addition
  1059.  
  1060.         (- <expr>...)  SUBTRACT A LIST OF NUMBERS OR NEGATE A SINGLE NUMBER
  1061.             <expr>      the numbers
  1062.             returns     the result of the subtraction
  1063.  
  1064.         (* <expr>...)  MULTIPLY A LIST OF NUMBERS
  1065.             <expr>      the numbers
  1066.             returns     the result of the multiplication
  1067.  
  1068.         (/ <expr>...)  DIVIDE A LIST OF NUMBERS
  1069.             <expr>      the numbers
  1070.             returns     the result of the division
  1071.  
  1072.         (1+ <expr>)  ADD ONE TO A NUMBER
  1073.             <expr>      the number
  1074.             returns     the number plus one
  1075.  
  1076.         (1- <expr>)  SUBTRACT ONE FROM A NUMBER
  1077.             <expr>      the number
  1078.             returns     the number minus one
  1079.  
  1080.         (rem <expr>...)  REMAINDER OF A LIST OF NUMBERS
  1081.             <expr>      the numbers
  1082.             returns     the result of the remainder operation
  1083.  
  1084.         (min <expr>...)  THE SMALLEST OF A LIST OF NUMBERS
  1085.             <expr>      the expressions to be checked
  1086.             returns     the smallest number in the list
  1087.  
  1088.         (max <expr>...)  THE LARGEST OF A LIST OF NUMBERS
  1089.             <expr>      the expressions to be checked
  1090.             returns     the largest number in the list
  1091.  
  1092.         (abs <expr>)  THE ABSOLUTE VALUE OF A NUMBER
  1093.             <expr>      the number
  1094.             returns     the absolute value of the number
  1095.  
  1096.         (random <n>)  COMPUTE A RANDOM NUMBER BETWEEN 1 and N-1
  1097.             <n>         the upper bound (integer)
  1098.             returns     a random number
  1099.         XLISP                 ARITHMETIC FUNCTIONS               Page 33
  1100.  
  1101.  
  1102.         (sin <expr>)  COMPUTE THE SINE OF A NUMBER
  1103.             <expr>      the floating point number
  1104.             returns     the sine of the number
  1105.  
  1106.         (cos <expr>)  COMPUTE THE COSINE OF A NUMBER
  1107.             <expr>      the floating point number
  1108.             returns     the cosine of the number
  1109.  
  1110.         (tan <expr>)  COMPUTE THE TANGENT OF A NUMBER
  1111.             <expr>      the floating point number
  1112.             returns     the tangent of the number
  1113.  
  1114.         (expt <x-expr> <y-expr>)  COMPUTE X TO THE Y POWER
  1115.             <x-expr>    the floating point number
  1116.             <y-expr>    the floating point exponent
  1117.             returns     x to the y power
  1118.  
  1119.         (exp <x-expr>)  COMPUTE E TO THE X POWER
  1120.             <x-expr>    the floating point number
  1121.             returns     e to the x power
  1122.  
  1123.         (sqrt <expr>)  COMPUTE THE SQUARE ROOT OF A NUMBER
  1124.             <expr>      the floating point number
  1125.             returns     the square root of the number
  1126.         XLISP              BITWISE LOGICAL FUNCTIONS             Page 34
  1127.  
  1128.  
  1129.         BITWISE LOGICAL FUNCTIONS
  1130.  
  1131.         (log-and <expr>...)  THE BITWISE AND OF A LIST OF NUMBERS
  1132.             <expr>      the numbers
  1133.             returns     the result of the and operation
  1134.  
  1135.         (log-ior <expr>...)  THE BITWISE INCLUSIVE OR OF A LIST OF NUMBERS
  1136.             <expr>      the numbers
  1137.             returns     the result of the inclusive or operation
  1138.  
  1139.         (log-xor <expr>...)  THE BITWISE EXCLUSIVE OR OF A LIST OF NUMBERS
  1140.             <expr>      the numbers
  1141.             returns     the result of the exclusive or operation
  1142.  
  1143.         (log-not <expr>)  THE BITWISE NOT OF A NUMBER
  1144.             <expr>      the number
  1145.             returns     the bitwise inversion of number
  1146.         XLISP                 RELATIONAL FUNCTIONS               Page 35
  1147.  
  1148.  
  1149.         RELATIONAL FUNCTIONS
  1150.  
  1151.         The relational functions can be used to compare integers,
  1152.         floating point numbers or strings.
  1153.  
  1154.         (< <e1> <e2>)  TEST FOR LESS THAN
  1155.             <e1>        the left operand of the comparison
  1156.             <e2>        the right operand of the comparison
  1157.             returns     the result of comparing <e1> with <e2>
  1158.  
  1159.         (<= <e1> <e2>)  TEST FOR LESS THAN OR EQUAL TO
  1160.             <e1>        the left operand of the comparison
  1161.             <e2>        the right operand of the comparison
  1162.             returns     the result of comparing <e1> with <e2>
  1163.  
  1164.         (= <e1> <e2>)  TEST FOR EQUAL TO
  1165.             <e1>        the left operand of the comparison
  1166.             <e2>        the right operand of the comparison
  1167.             returns     the result of comparing <e1> with <e2>
  1168.  
  1169.         (/= <e1> <e2>)  TEST FOR NOT EQUAL TO
  1170.             <e1>        the left operand of the comparison
  1171.             <e2>        the right operand of the comparison
  1172.             returns     the result of comparing <e1> with <e2>
  1173.  
  1174.         (>= <e1> <e2>)  TEST FOR GREATER THAN OR EQUAL TO
  1175.             <e1>        the left operand of the comparison
  1176.             <e2>        the right operand of the comparison
  1177.             returns     the result of comparing <e1> with <e2>
  1178.  
  1179.         (> <e1> <e2>)  TEST FOR GREATER THAN
  1180.             <e1>        the left operand of the comparison
  1181.             <e2>        the right operand of the comparison
  1182.             returns     the result of comparing <e1> with <e2>
  1183.         XLISP                   STRING FUNCTIONS                 Page 36
  1184.  
  1185.  
  1186.         STRING FUNCTIONS
  1187.  
  1188.         (char <string> <index>)  EXTRACT A CHARACTER FROM A STRING
  1189.             <string>    the string
  1190.             <index>     the string index (zero relative)
  1191.             returns     the ascii code of the character
  1192.  
  1193.         (string <expr>)  MAKE A STRING FROM AN INTEGER ASCII VALUE
  1194.             <expr>      the integer
  1195.             returns     a one character string
  1196.  
  1197.         (strcat [<expr>]...)  CONCATENATE STRINGS
  1198.             <expr>      the strings to concatenate
  1199.             returns     the result of concatenating the strings
  1200.  
  1201.         (substr <expr> <sexpr> [<lexpr>]) EXTRACT A SUBSTRING
  1202.             <expr>      the string
  1203.             <sexpr>     the starting position
  1204.             <lexpr>     the length (default is rest of string)
  1205.             returns     substring starting at <sexpr> for <lexpr>
  1206.         XLISP                INPUT/OUTPUT FUNCTIONS              Page 37
  1207.  
  1208.  
  1209.         INPUT/OUTPUT FUNCTIONS
  1210.  
  1211.         (read [<source> [<eof> [<rflag>]]])  READ AN XLISP EXPRESSION
  1212.             <source>    the input source (default is standard input)
  1213.             <eof>       the value to return on end of file (default is nil)
  1214.             <rflag>     recursive read flag (default is nil)
  1215.             returns     the expression read
  1216.  
  1217.         (print <expr> [<sink>])  PRINT A LIST OF VALUES ON A NEW LINE
  1218.             <expr>      the expressions to be printed
  1219.             <sink>      the output sink (default is standard output)
  1220.             returns     the expression
  1221.  
  1222.         (prin1 <expr> [<sink>])  PRINT A LIST OF VALUES
  1223.             <expr>      the expressions to be printed
  1224.             <sink>      the output sink (default is standard output)
  1225.             returns     the expression
  1226.  
  1227.         (princ <expr> [<sink>])  PRINT A LIST OF VALUES WITHOUT QUOTING
  1228.             <expr>      the expressions to be printed
  1229.             <sink>      the output sink (default is standard output)
  1230.             returns     the expression
  1231.  
  1232.         (terpri [<sink>])  TERMINATE THE CURRENT PRINT LINE
  1233.             <sink>      the output sink (default is standard output)
  1234.             returns     nil
  1235.  
  1236.         (flatsize <expr>)  LENGTH OF PRINTED REPRESENTATION USING PRIN1
  1237.             <expr>      the expression
  1238.             returns     the length
  1239.  
  1240.         (flatc <expr>)  LENGTH OF PRINTED REPRESENTATION USING PRINC
  1241.             <expr>      the expression
  1242.             returns     the length
  1243.         XLISP                  FILE I/O FUNCTIONS                Page 38
  1244.  
  1245.  
  1246.         FILE I/O FUNCTIONS
  1247.  
  1248.         (openi <fname>)  OPEN AN INPUT FILE
  1249.             <fname>     the file name string or symbol
  1250.             returns     a file pointer
  1251.  
  1252.         (openo <fname>)  OPEN AN OUTPUT FILE
  1253.             <fname>     the file name string or symbol
  1254.             returns     a file pointer
  1255.  
  1256.         (close <fp>)  CLOSE A FILE
  1257.             <fp>        the file pointer
  1258.             returns     nil
  1259.  
  1260.         (read-char [<source>])  READ A CHARACTER FROM A FILE OR STREAM
  1261.             <source>    the input source (default is standard input)
  1262.             returns     the character (integer)
  1263.  
  1264.         (peek-char [<flag> [<source>]])  PEEK AT THE NEXT CHARACTER
  1265.             <flag>      flag for skipping white space (default is nil)
  1266.             <source>    the input source (default is standard input)
  1267.             returns     the character (integer)
  1268.  
  1269.         (write-char <ch> [<sink>])  WRITE A CHARACTER TO A FILE OR STREAM
  1270.             <ch>        the character to put (integer)
  1271.             <sink>      the output sink (default is standard output)
  1272.             returns     the character (integer)
  1273.  
  1274.         (read-line [<source>])  READ A LINE FROM A FILE OR STREAM
  1275.             <source>    the input source (default is standard input)
  1276.             returns     the input string
  1277.         XLISP                   SYSTEM FUNCTIONS                 Page 39
  1278.  
  1279.  
  1280.         SYSTEM FUNCTIONS
  1281.  
  1282.         (load <fname> [<vflag> [<pflag>]])  LOAD AN XLISP SOURCE FILE
  1283.             <fname>     the filename string or symbol
  1284.             <vflag>     the verbose flag (default is t)
  1285.             <pflag>     the print flag (default is nil)
  1286.             returns     the filename
  1287.  
  1288.         (transcript [<fname>])  CREATE A FILE WITH A TRANSCRIPT OF A SESSION
  1289.             <fname>     file name string or symbol
  1290.                         (if missing, close current transcript)
  1291.             returns     t if the transcript is opened, nil if it is closed
  1292.  
  1293.         (gc)  FORCE GARBAGE COLLECTION
  1294.             returns     nil
  1295.  
  1296.         (expand <num>)  EXPAND MEMORY BY ADDING SEGMENTS
  1297.             <num>       the number of segments to add
  1298.             returns     the number of segments added
  1299.  
  1300.         (alloc <num>)  CHANGE NUMBER OF NODES TO ALLOCATE IN EACH SEGMENT
  1301.             <num>       the number of nodes to allocate
  1302.             returns     the old number of nodes to allocate
  1303.  
  1304.         (mem)  SHOW MEMORY ALLOCATION STATISTICS
  1305.             returns     nil
  1306.  
  1307.         (type-of <expr>)  RETURNS THE TYPE OF THE EXPRESSION
  1308.             <expr>      the expression to return the type of
  1309.             returns     nil if the value is nil otherwise one of the symbols:
  1310.                           :SYMBOL for symbols
  1311.                           :OBJECT for objects
  1312.                           :CONS   for conses
  1313.                           :SUBR   for built-ins with evaluated arguments
  1314.                           :FSUBR  for built-ins with unevaluated arguments
  1315.                           :STRING for strings
  1316.                           :FIXNUM for integers
  1317.                           :FLONUM for floating point numbers
  1318.                           :FILE   for file pointers
  1319.                           :ARRAY  for arrays
  1320.  
  1321.         (peek <addrs>)  PEEK AT A LOCATION IN MEMORY
  1322.             <addrs>     the address to peek at (integer)
  1323.             returns     the value at the specified address (integer)
  1324.  
  1325.         (poke <addrs> <value>)  POKE A VALUE INTO MEMORY
  1326.             <addrs>     the address to poke (integer)
  1327.             <value>     the value to poke into the address (integer)
  1328.             returns     the value
  1329.  
  1330.         (address-of <expr>)  GET THE ADDRESS OF AN XLISP NODE
  1331.             <expr>      the node
  1332.             returns     the address of the node (integer)
  1333.         XLISP                   SYSTEM FUNCTIONS                 Page 40
  1334.  
  1335.  
  1336.         (exit)  EXIT XLISP
  1337.             returns     never returns
  1338.  
  1339.